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1.0 Document History 


Date Document Version Document Description / 
Changes to document 

1/8/08 1.0 Document Creation 

5/5/09 1.1 Update on error code 

12/3/2013 | 1.2 Update on DN URL Transaction Status 

1/1/2014 1.3 Update on Receive Reply 

2.0 Abbreviation 

Abbreviation Full Description and explanation 

CP Content Provider — Customers connecting to onewaysms gateway 

HTTP Hyper Text Transport Protocol — Protocol used for CP to communicate 
with onewaysms gateway 

MSISDN Mobile Station International ISDN number 

SMS Short Messaging Service 

MT Mobile Terminating 

MT URL onewaysms.sg’s sms platform MT URL (URL for Content Provider to 
interface with onewaysms sms gateway to send out MT) 

DN Delivery Notification. This is the notification from the Telco to indicate 
the status of the SMS 
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3.0 Introduction 
This document is intended to be used by developers, technical architect, designer who wish to 


develop applications or connect their platforms to interface with onewaysms’s sms gateway 
through HTTP connectivity. 


4.0 System Requirement 
1. Content Provider may use any web based programming language that supports HTTP 


protocol 
2. Onewaysms gateway will be listening on port 10002 or port 80 
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5.0 API List 


onewaysms gateway expose 4 API for CP to utilize 


1. 


E tes 


Send MT message 

Check transaction status 
Check credit balance 

DN URL Transaction status 
Receive Reply 


Guide to integrate with onewaysms gateway 


5.1 


Send MT message 


Content | 20Send MT Message | Onewaysms 


gateway 3.0 Deliver SMS 
a ee 


Provider 


2.0 Receive result 
in body 


Diagram 1: Send MT Message 


To send MT, CP would need to call MT URL with the appended parameter. (MT URL can 
be obtain from API section in your account) 


Below are the HTTP parameter that are required to be appended to MT URL 


Parameter Data Description 
Name Format 
apiusername String Username for your API (can be obtain under API 


section once you have log into your account) 
Note : API username is different from your web 
username) 

apipassword String Password for your API (can be obtain under API 
section once you have log into your account) 
Note : API username is different from your web 
username) 

mobileno String Phone number of recipient. Phone number 
must include country code. 

Example : 6581234567 

10 mobile numbers can be included in this field 
separated with commas (,). 

Eg. 6581234567,6597654321 

senderid String Refer to sender. Field can take up to 11 
alphanumeric characters. 
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languagetype String Indicated the type of sms sent: 

“1” — Normal Text message (160 characters as 1 
MT) 

“2” — Unicode Text message (70 characters as 1 
MT) 


For languagetype 2, refer to Appendix 1 for 
example on conversion 


message String Content of the SMS. 


Example, if languagetype set to 1, and message 
has content with length 200, 2 SMS will be sent. 


We can combine SMS. We need 7 characters to 
combine. Below are the character count 

1 SMS = 160 characters 

2 SMS = 306 characters (14 characters for joining) 
3 SMS = 459 characters (21 characters for joining) 


We recommend sending up to maximum 3 SMS 
long 


Once onewaysms gateway receives a MT request, it will return a HTTP 200 response to 
CP 
e If the value is other than 200, then it is a failed request. 
e If the value is 200, CP is required to extract the message body for the result 
e If the result is a negative value, some of the MT parameters are invalid (refer 
below for details) 
e If the result is a positive value, it means our gateway successfully receive it. The 
result is the MT ID. (If you would like to check on transaction status, you would 
need to store this ID) 


Below are the result that will return on the message body 

Result Description 

>0 Positive value — Success 
If multiple numbers are sent in the same request, result will display 
multiple MT ID, For example, 200806150001,200806150002 


-100 apipassname or apipassword is invalid 
-200 senderid parameter is invalid 

-300 mobileno parameter is invalid 

-400 languagetype is invalid 
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-500 Invalid characters in message 
-600 Insufficient credit balance 


Refer to Appendix 2 on URL example on sending MT 


Check transaction status (optional to implement) 


Content 1.0 check transaction status Onewaysms 
— 


Provider gateway 


2.0 Receive result 
in body 


Diagram 2: Check transaction status 


Once bulk MT is delivered to subscriber, Content Provider may check transaction status 
by calling bulk check URL (Bulk check URL can be obtain from API section in your 
account) 


Below are the HTTP parameter that are required to be appended to MT URL 


Parameter Data Description 

Name Format 

mtid String MT ID received from onewaysms gateway when 
sending MT previously 


Below are the result that will return on the message body 


Result Description 

0 Success receive on mobile handset 
100 Message delivered to Telco 

-100 mtid invalid / not found 

-200 Message sending fail 


Refer to Appendix 3 on URL example on check transaction status 
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Check Credit Balance (optional to implement) 


Content 1.0 Check credit balance Onewaysms 


Provider gateway 


2.0 Receive result 
in body 


Diagram 3 : Check credit balance 


Content Provider can check credit by calling check balance URL . (Check balance URL can 
be obtain from API section in your account) 


Parameter Data Description 
Name Format 
apiusername String Username for your API (can be obtain under API 


section once you have log into your account) 
Note : API username is different from your web 
username) 

apipassword String Password for your API (can be obtain under API 
section once you have log into your account) 
Note : API username is different from your web 


username) 


Below are the result that will return on the message body 


Result Description 

0 or positive SMS Credit balance in your account 
value 

-100 apipassname or apipassword is invalid 


Refer to Appendix 4 on URL example on check credit balance 


Confidential and Proprietary 8 


(GJNEWAY Sms’ a 


5.4 DN URL Transaction Status (optional to implement) 


Onewaysms 1.0 Return Status in DN URL Content 


gateway Provider 


2.0 Receive HTTP 200 
I) 


Diagram 4 : DN URL Transaction Status 


One Way SMS will update the status of the SMS Transaction by calling Content 
Provider’s DN URL. (Content Provider can set the DN URL from your own account) 


Parameter Data Description 

Name Format 

mtid String MT ID received from onewaysms gateway when 
sending MT previously 

status int 1 = success 
-1 = fail 
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5.5 Receive Reply (optional to implement) 


1.0 Call Reply URL Content 
l 


Onewaysms 
Provider 


gateway 


2.0 Receive HTTP 200 
I) 


Diagram 5 : Receive Reply 


One Way SMS will update the status of the SMS Transaction by calling Content 
Provider’s Reply URL. (Content Provider can set the Reply URL from your own account) 
Below are the steps 

1. Log into your account 

2. On the top menu, select “SMS”, then “Reply Setting” 

3. Select URL as the Reply Setting and enter your Reply URL 


Parameter Data Description 

Name Format 

mtid String MT ID received from onewaysms gateway when 
sending MT previously 

mobile String Mobile number that send reply. Eg 6581234567 

message String The content of the reply message 
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6.0 Appendix 
Appendix 1 
For send with languagetype 2, you would need to convert the message to hexadecimal value 


Below are examples on the conversion 

Letter “a” : hexadecimal value is 0061 

Chinese character “A” : hexadecimal value is 4EBA 

Note : each character must be converted to 4 hexadecimal value. Using example “a”, some 


software will convert to 61, you would need to append “00” to make it “0061” 


Appendix 2 


Example sending SMS with languagetype 1 
http://mturl?apiusername=123 &apipassword=123 &mobileno=6581234567&senderid=onewa 


sms&languagetype=1&message=hello 


Example sending SMS with languagetype 2 
http://mturl?apiusername=123 &apipassword=123 &mobileno=6581234567&senderid=onewa 


sms&languagetype=2&message=00680065006CO06CO06F 


Note : hello converted to hexadecimal is OO680065006COO6COO6F 


Appendix 3 


Example calling check transaction status URL 


http://checkstatusurl?mtid=808010000123 


Appendix 4 

Example calling check credit balance 
http://checkcrediturl?apiusername=123&apipassword=123 
Appendix 5 


Example of DN URL calling 
http://dnurl?mtid=808010000123&status=1 
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